home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / comms / other / pronet / developer / autodoc / pronet.doc next >
Text File  |  1999-06-14  |  6KB  |  175 lines
  1. TABLE OF CONTENTS
  2.  
  3. pronet.device/--Overview--
  4. pronet.device/CloseDevice
  5. pronet.device/CMD_WRITE
  6. pronet.device/OpenDevice
  7. pronet.device/ReceivedData
  8. pronet.device/--Overview--                         pronet.device/--Overview--
  9.  
  10.  >> GENERAL INFORMATION <<
  11.  
  12.  The device is able to handle several Units, which are defined in the
  13.  `devs:pronet/.config' file. Each Unit corresponds to a certain driver
  14.  and interface. The Units are subdivided into Ports, which are channels
  15.  between two sides of one Unit. This way two application systems may work
  16.  through the same connection without interfering each other.
  17.  
  18.  pronet.device is *not* a SANA-II compliant networking device, and it is not
  19.  compatible to any other exec device, because it's got some very strange
  20.  behaviour regarding incoming data.  Sometimes it is useful, sometimes it is
  21.  not, but I will not change this anyway:  CMD_READ is not supported, instead
  22.  of that, when opening the device, you specify a MsgPort to which all
  23.  incoming data will be sent automatically, if you want it or not!
  24.  
  25.  pronet.device v37 is incompatible to ProNET applications written
  26.  earlier, see below. I'm sorry for that, but I've not heard from people
  27.  using this device anyway ;-)
  28.  
  29.  >> ERROR CODES <<
  30.  
  31.  pronet.device v37 can return one of the following error codes after
  32.  OpenDevice():
  33.  
  34.  PNDERR_PORTEXISTS
  35.     You've tried to open up a Port which is already in use.
  36.  
  37.  PNDERR_DRIVERTROUBLE
  38.     The driver of the Unit you requested can not be started.
  39.     You can request a more detailed error message by setting the
  40.     according bit in OpenDevice()/Flags. pnr_Data must then point to
  41.     a buffer provided by you. The string will not exceed 63 characters
  42.     plus the terminating zero. If no error occurs, the buffer will
  43.     not be changed!
  44.  
  45.  PNDERR_UNIT_NOT_DEFINED
  46.     The Unit you requested is missing a definition in the config file.
  47.  
  48.  >> CHANGES SINCE V3 <<
  49.  
  50.  v37: Write doesn't support two chunks anymore, Write can fail
  51.     with PNDERR_DESTINATION_GONE now, no more #?ConfigString() in order
  52.     to keep the configuration file tidy. Structure of received data
  53.     has changed. PNB_ERRORSTRING.
  54.  
  55.  >> WRITING DRIVERS <<
  56.  
  57.  You find information on this subject in the other autodoc file supplied
  58.  with the ProNET distribution.
  59.  
  60. pronet.device/CloseDevice                           pronet.device/CloseDevice
  61.  
  62.    NAME   
  63.     CloseDevice -- Close a port of a certain ProNET Unit.
  64.  
  65.    SYNOPSIS
  66.     CloseDevice(PNRequest);
  67.                    A1
  68.  
  69.    FUNCTION
  70.     This is an exec.library call.
  71.  
  72.     This function terminates access to the corresponding ProNET Unit.
  73.     Since the Unit is not shut down automatically, even if you were
  74.     the last user of it, a RemDevice() would be the right thing to
  75.     do after closing pronet.device.
  76.  
  77.    INPUTS
  78.     PNRequest - A pointer to a previously opened ProNET IO Request.
  79.  
  80.    EXAMPLE
  81.     This code can force a specified device to try and expunge.
  82.     Of course, if the device is in use nothing will happen:
  83.  
  84.     void FlushDevice(name)
  85.     char  *name;
  86.     {
  87.     struct Device *result;
  88.  
  89.         Forbid();
  90.         if(result=(struct Device *)FindName(&SysBase->DeviceList,name))
  91.         RemDevice(result);
  92.         Permit();
  93.     }
  94.  
  95.    SEE ALSO
  96.     exec.library/CloseDevice(), exec.library/RemDevice()
  97.  
  98. pronet.device/CMD_WRITE                               pronet.device/CMD_WRITE
  99.  
  100.    NAME   
  101.     Write -- send output to ProNET Port.
  102.  
  103.    FUNCTION
  104.     This command causes a packet of data to be written out the ProNET
  105.     Port/Unit. The number of characters is specified in pnr_Length.
  106.  
  107.    IO REQUEST
  108.     io_Command - CMD_WRITE
  109.     pnr_Data - pointer to block of data to transmit
  110.     pnr_Length - number of characters to transmit. MUST BE EVEN AND MUST
  111.         NOT BE GREATER THAN 0x4000!
  112.  
  113.    RESULTS
  114.     io_Error - if the Write succeeded, then io_Error will be zero.
  115.         The only other possible error code is PNDERR_DESTINATION_GONE.
  116.  
  117. pronet.device/OpenDevice                             pronet.device/OpenDevice
  118.  
  119.    NAME   
  120.     OpenDevice -- Open up a new port of a certain ProNET Unit.
  121.  
  122.    SYNOPSIS
  123.     error = OpenDevice("pronet.device", unit, ioRequest, flags);
  124.        D0                  A0              D0    A1         D1
  125.  
  126.     BYTE OpenDevice(STRPTR, ULONG, struct PNRequest*, ULONG);
  127.  
  128.    FUNCTION
  129.     This is an exec.library call.
  130.  
  131.     Hey, what do you think it does?!??
  132.  
  133.    INPUTS
  134.     unit - This number must be defined in the `DEVS:ProNET/.config' file,
  135.         otherwise OpenDevice() will return PNDERR_UNIT_NOT_DEFINED.
  136.     ioRequest - A pointer to an initialized (see below) PNRequest block.
  137.     flags - As described in the overview page, you have the option
  138.         to get extensive error messages when setting a bit here.
  139.         The bit is defined as PNB_ERRORSTRING (the PNF_ definition also
  140.         exists).
  141.  
  142.     Two components of the PNRequest must be initialized before calling
  143.     OpenDevice():
  144.  
  145.     pnr_MsgPort - pointer to a MsgPort where incoming data is sent to.
  146.     pnr_NetSourcePort - The port number you want to open.
  147.  
  148.    RESULT
  149.     error - zero if everything went o.k., otherwise an error code
  150.         as defined in exec/errors.h or devices/pronet.h.
  151.  
  152.    NOTES
  153.     The *one and only* valid port numbers are 0x0001 to 0x7fff. If you
  154.     want a special number above 0x7fff reserved for your application,
  155.     please contact me!
  156.  
  157.     If you don't have any special preferences for your port number,
  158.     you can use PNP_NEXTFREE to let pronet.device assign you the next
  159.     free one (it will be put into pnr_NetSourcePort then).
  160.  
  161. pronet.device/ReceivedData                         pronet.device/ReceivedData
  162.  
  163.  Received data will be sent to the MsgPort you specified in pnr_MsgPort
  164.  when opening the device. You can not change it after opening.
  165.  mn_Length, as opposed to pre-v37, contains the length of the whole Message
  166.  structure. The first word of mn_Node.ln_Name contains the source ProNET
  167.  Port, the second word contains the destination port. The data comes behind
  168.  the Message structure.
  169.  
  170.  This Message must be replied as soon as there is no use for it any more.
  171.  
  172.  If there is incoming data but pronet.device can't allocate the Message
  173.  structure, the packet is lost!
  174.  
  175.